home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / u_man / cat1 / prof.z / prof
Text File  |  1998-10-30  |  41KB  |  793 lines
  1.  
  2.  
  3.  
  4. PPPPRRRROOOOFFFF((((1111))))                                                                PPPPRRRROOOOFFFF((((1111))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      prof - analyze SpeedShop performance data
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      pppprrrrooooffff [options] [speedshop_data_file  | pixie_counts_file] ...
  13.      pppprrrrooooffff [options] executable-name [speedshop_data_file  | pixie_counts_file]
  14.      ...
  15.  
  16. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  17.      _p_r_o_f analyzes one or more data files generated by the SpeedShop
  18.      performance tools and produces a report. (Note that most reports are
  19.      formatted with long lines, and should be viewed in a window that is 135
  20.      characters wide, and printed in wide format.)  The second form is used to
  21.      analyze data files generated by the SpeedShop performance tools if the
  22.      target program is not in the same directory as the data files (in which
  23.      case <executable-name> should be the path to the target program).
  24.  
  25.      Multiple files can be included only if they are recorded from the same
  26.      executable with the same experiment type.  The default listing for all
  27.      experiments lists functions in descending order of the appropriate
  28.      exclusive (meaning from within the function, rather than included from
  29.      calls it makes) performance metric.  (See below, FUNCTION LIST.)  Options
  30.      allow sorting by calls or by inclusive metrics, for those experiments
  31.      where the recorded data supports them.  Where applicable, the
  32.      -_b[_u_t_t_e_r_f_l_y] option also produces a listing of callers and callees for
  33.      each function, with attribution percentages and time or counts.  (See
  34.      below, BUTTERFLY LIST.)  Addition listings may also be generated; see
  35.      below.
  36.  
  37.      The current implementation supports the following SpeedShop experiments:
  38.  
  39.      uuuusssseeeerrrrttttiiiimmmmeeee (callstack profiling, user+system time trigger) causes the
  40.      program to be interrupted every 30 milliseconds during its running time
  41.      (user or system mode, but not including any wait time), and to record the
  42.      callstack at each interrupt.  It can show both inclusive and exclusive
  43.      time.  uuuusssseeeerrrrttttiiiimmmmeeee data is statistical in nature, and will show some
  44.      variance from run to run.
  45.  
  46.      ttttoooottttaaaallllttttiiiimmmmeeee (callstack profiling, wall-clock time trigger) causes the
  47.      program to be interrupted every 30 milliseconds of wall-clock time during
  48.      the run, and to record the callstack at each interrupt.  It can show both
  49.      inclusive and exclusive time.  ttttoooottttaaaallllttttiiiimmmmeeee data is statistical in nature,
  50.      and will show some variance from run to run.
  51.  
  52.      [[[[ffff]]]]ppppccccssssaaaammmmpppp[[[[xxxx]]]] asks the kernel to look at the user PC every 10
  53.      milliseconds, and record a histogram of the value of the program counter
  54.      at each clock tick, using 16-bit bins, one for each PC value.  It can
  55.      only show exclusive data, that is data about where the program counter
  56.      was, not the callstack to get there.  The [[[[ffff]]]] prefix specifies 1
  57.      millisecond profiling, instead of 10 milliseconds.  The [[[[xxxx]]]] suffix
  58.      specifies 32-bit count bins, instead of 16-bit.  ****ppppccccssssaaaammmmpppp**** data is
  59.      statistical in nature, and will show some variance from run to run.
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. PPPPRRRROOOOFFFF((((1111))))                                                                PPPPRRRROOOOFFFF((((1111))))
  71.  
  72.  
  73.  
  74.      ****____hhhhwwwwcccc asks the kernel to look at the user PC every time the hardware
  75.      performance counter specified by the experiment overflows, and record a
  76.      histogram of the value of the program counter at overflow.  These
  77.      experiments can only be run on R10000 machines; other machines do not
  78.      have the hardware performance counters.  There are a number of these
  79.      experiments defined; see speedshop(1).  They can only show exclusive
  80.      data, that is data about where the program counter was, not the callstack
  81.      to get there.  The particular counter used and its overflow value are
  82.      specified in the experiment.  Some of the Hardware Performance counter
  83.      sampling experiments are statistical in nature, and will show some
  84.      variance from run to run; others are exact, provided that the program
  85.      executes the exact same sequence of instructions.
  86.  
  87.      Among the interesting counter prefixes to use are:
  88.       ccccyyyy____ for cycle counting;
  89.       ggggiiii____ for graduated instructions;
  90.       iiiicccc____ for primary instruction cache misses;
  91.       ssssiiiicccc____ for secondary instruction cache misses;
  92.       ddddcccc____ for primary data cache misses;
  93.       sssscccc____ for secondary data cache misses;
  94.       ttttllllbbbb____ for TLB misses;
  95.       ggggffffpppp____ for graduated floating-point instructions; and
  96.       ffffsssscccc____ for failed store-conditional instructions.
  97.  
  98.      ****____hhhhwwwwccccttttiiiimmmmeeee (callstack profiling, R10K hardware counter overflow trigger)
  99.      causes the program to be interrupted at every _N overflows of the
  100.      particular counter and to record the callstack at each interrupt.  The
  101.      value of _N depends on the particular counter chosen.  It can take the
  102.      same set of prefixes as above, but since callstacks are recorded, it can
  103.      show both inclusive and exclusive time.  ****____hhhhwwwwccccttttiiiimmmmeeee data is statistical in
  104.      nature, and will show some variance from run to run.
  105.  
  106.      iiiiddddeeeeaaaallll causes the code to be instrumented to count the number of times
  107.      each basic block is executed.  (A _b_a_s_i_c _b_l_o_c_k is a region of the program
  108.      that can be entered only at the beginning and exited only at the end.)
  109.      The data recorded also contains counts for all function pointer calls.
  110.      From this data, a machine model is used to compute the exclusive time
  111.      (cycles) spent in each function.
  112.  
  113.      Inclusive time computations, performed when the -_b[_u_t_t_e_r_f_l_y] flag is
  114.      specified to _p_r_o_f, calculates the exclusive time for each routine as
  115.      above, and then propagates the time to each caller of each routine in
  116.      proportion to the number of calls.  For example, if sin(x) takes 1000
  117.      cycles, and its callers - procedures foo() and bar() - call it  25 and 75
  118.      times respectively, 250 cycles are attributed  to foo() and 750 to bar().
  119.      By propagating cycles this way, __start() should end up with all the
  120.      cycles counted in the program.
  121.  
  122.      Note that the propagation according to the number of calls may not be
  123.      reasonable for some routines, and may lead to misleading reports.  For
  124.      example, if a matrix-multiply routine is substituted for sin(x) in the
  125.      above example, and bar's calls are for 2X2 matrices, while foo's calls
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. PPPPRRRROOOOFFFF((((1111))))                                                                PPPPRRRROOOOFFFF((((1111))))
  137.  
  138.  
  139.  
  140.      are for 100X100 matrices, the attribution distributes 3/4 of the time to
  141.      bar, whereas nearly all the time really should be attributed to foo.
  142.  
  143.      ffffppppeeee asks the floating-point exception library to trace all floating-point
  144.      exceptions, with their callstacks.  These experiments show listings
  145.      similar to those for uuuusssseeeerrrrttttiiiimmmmeeee experiments, except the data reported is a
  146.      count of floating-point exceptions, rather than projected CPU time.
  147.  
  148.      iiiioooo asks for a trace of all IO calls made by the program.  These
  149.      experiments will show calls attributed to functions, and with
  150.      -_b[_u_t_t_e_r_f_l_y], can show which functions made which calls.
  151.  
  152. OOOOUUUUTTTTPPPPUUUUTTTT RRRREEEEPPPPOOOORRRRTTTTSSSS
  153.      _p_r_o_f writes an analysis of the performance data to stdout.  The first
  154.      thing in the list is a summary of the experiment, and description of the
  155.      environment in which it was recorded.  That is followed by a header that
  156.      summarized the particular data recorded.  Following that is the function
  157.      list;  if -_b[_u_t_t_e_r_f_l_y] is given, and the data supports it, a butterfly
  158.      list will be presented.
  159.  
  160.      If -_h[_e_a_v_y] or -_l[_i_n_e_s] is given, for ****ppppccccssssaaaammmmpppp****, ****hhhhwwwwcccc, and iiiiddddeeeeaaaallll
  161.      experiments, a report of data at the source line level is appended,
  162.      sorted by the performance metric computed on a line basis, or by
  163.      functions, and then by line numbers within a function, respectively.  For
  164.      other experiments, these options are ignored.
  165.  
  166.      If -_b_a_s_i_c_b_l_o_c_k_s is given, for iiiiddddeeeeaaaallll experiments only, A report of data at
  167.      the basic-block level is appended.  If -_a_r_c_h_i_n_f_o is given, also for iiiiddddeeeeaaaallll
  168.      experiments only, a summary report of register usage, instruction usage,
  169.      and various other statistics is appended.  For other experiments, these
  170.      options are ignored.
  171.  
  172.      If -_d_s_o_l_i_s_t is given, a list of the DSOs used by the program is appended.
  173.  
  174.      If -_u_s_a_g_e is given, a summary of the resources used by the program is
  175.      appended.
  176.  
  177. FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN LLLLIIIISSSSTTTT
  178.      The default output for any experiment is a function list, sorted in the
  179.      order of exclusive values of the primary metric--the performance cost of
  180.      the function, as computed from the data recorded.  For many experiments,
  181.      this metric is a time, printed in the report in seconds; for others, it
  182.      is a count of events-FPEs, IO calls, or R10K counter overflow counts.
  183.  
  184.      The report begins with a legend line, naming each of the columns of data.
  185.      Each line in the list has an index; if -_b[_u_t_t_e_r_f_l_y] is not specified, the
  186.      index will be in numerical order; if it is specified, the index will be
  187.      in order of functions as sorted by the inclusive metric.  The index
  188.      serves as a poor-person's hyperlink through the butterfly, and between
  189.      the butterfly and the function list.
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. PPPPRRRROOOOFFFF((((1111))))                                                                PPPPRRRROOOOFFFF((((1111))))
  203.  
  204.  
  205.  
  206.      To the left of the index, is the primary metric, followed by its
  207.      representation as a percentage of the whole program, followed by the
  208.      cumulative percentage up to that point in the list.  The next two columns
  209.      are inclusive value of the metric., and its representation as a
  210.      percentage.
  211.  
  212.      Following that may be additional columns of data, as appropriate to the
  213.      particular data recorded.  Finally, rightmost on the line will be the
  214.      name of the function, and the DSO and source file basenames.
  215.  
  216. BBBBUUUUTTTTTTTTEEEERRRRFFFFLLLLYYYY LLLLIIIISSSSTTTT
  217.      The butterfly list is a set of records that show the callers and callees
  218.      of each function.  The list is sorted in the order of inclusive values of
  219.      the primary metric.  For each function, its callers are shown above it,
  220.      and its callees below.  The center line is for the function itself, and
  221.      shows the index at the beginning and end of the line.  The second and
  222.      third columns are the inclusive percentages of the primary metric and its
  223.      absolute value.  The next two columns of the center line are the
  224.      exclusive percentage and the exclusive value of the metric, followed by
  225.      the function identification.
  226.  
  227.      Callees are shown below the function, with attribution percentages and
  228.      values lined up below the self percentages and values of the center
  229.      function.  In absolute mode (the default), the percentages, including the
  230.      center node's self value, should add up to the inclusive percentage of
  231.      the center node;  in relative mode, specified with -_r_e_l[_a_t_i_v_e] flag, the
  232.      percentages should add up to 100 %.  In either mode, the attribution
  233.      values should add up to the inclusive time of the central function.  The
  234.      attribution data for callees is followed by the inclusive value for that
  235.      caller and callsite, followed by the callsite identification, with an
  236.      address, a source file, and a line number.  For callees, the source file
  237.      will be that of the central function.
  238.  
  239.      The callers are shown above the central function, also with attribution
  240.      percentages and values, but these have a different meaning, and are
  241.      aligned with the central nodes inclusive values to so indicate.  The
  242.      attribution percentage and value in a caller's line represents the
  243.      percentage and value, respectively, of the central function's metric that
  244.      was attributed to that callsite.  In absolute mode, the percentages
  245.      should add up to the central function's percentage; in relative mode,
  246.      they should add up to 100%.  The attribution values should add to the
  247.      central function's values.  The attribution data for callers is followed
  248.      by the inclusive value for that caller and callsite, followed by the
  249.      callsite identification, with an address, a source file, and a line
  250.      number.  For callers, the source file will be that of the calling
  251.      function.
  252.  
  253. LLLLIIIINNNNEEEE----LLLLEEEEVVVVEEEELLLL LLLLIIIISSSSTTTTSSSS
  254.      When invoked with the -_h[_e_a_v_y] or -_l[_i_n_e_s] arguments, a list of line-
  255.      level data is produced.  When -_h[_e_a_v_y] is used, the line list is sorted
  256.      by the primary metric associated with each line, with lines from the
  257.      various DSOs and source files intermixed.  When -_l[_i_n_e_s] is used, the
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. PPPPRRRROOOOFFFF((((1111))))                                                                PPPPRRRROOOOFFFF((((1111))))
  269.  
  270.  
  271.  
  272.      lines are sorted based on the function they came from, with all lines
  273.      with non-zero values from each function printed before any lines from the
  274.      next most important function.
  275.  
  276.      For each line, the leftmost column contains the value for the primary
  277.      metric computed from the particular experiment, followed by its
  278.      representation as a percentage, followed by the cumulative percentage
  279.      over all lines printed thus far.  These data are followed by any
  280.      additional metrics for the particular experiment, and then by the name of
  281.      the function, its DSO, file and line number.
  282.  
  283. BBBBAAAASSSSIIIICCCC BBBBLLLLOOOOCCCCKKKK LLLLIIIISSSSTTTT
  284.      When invoked with the -_b_a_s_i_c_b_l_o_c_k_s argument (applicable iiiiddddeeeeaaaallll experiments
  285.      only), a list of all the basic blocks in the program that were executed
  286.      is generated.  It is preceded by a header, and a column header line, and
  287.      then the list of basic blocks, in order of total cycles.
  288.  
  289.      Each basic block is printed with its index, the number of cycles per
  290.      execution of the block, the count of executions, the total cycles, and
  291.      the total cycles represented as a percentage.  Trailing that on each
  292.      line, is the function, and the address of the beginning of the line, with
  293.      the DSO, source file, and source line number.
  294.  
  295. AAAARRRRCCCCHHHHIIIITTTTEEEECCCCTTTTUUUURRRRAAAALLLL IIIINNNNFFFFOOOORRRRMMMMAAAATTTTIIIIOOOONNNN RRRREEEEPPPPOOOORRRRTTTT
  296.      When invoked with the -_a_r_c_h_i_n_f_o argument (applicable iiiiddddeeeeaaaallll experiments
  297.      only), a list of various metrics concerning execution of the program is
  298.      printed.  The report consists of a header, and a number of subsections,
  299.      each with the appropriate headers.
  300.  
  301.      For integer registers, counts are printed of the number of times each
  302.      register was used, and its percentage, the number of times each register
  303.      was used as a base register, and its percentage, and the number of times
  304.      each register is used as a destination register, and its percentage.  For
  305.      floating point registers, the same data, less the base count statistics,
  306.      is printed.
  307.  
  308.      Following the register usage statistics, a number of counts of
  309.      instruction types or sequences are printed, each with a description,
  310.      followed by a list of all the different instructions used, sorted by the
  311.      number of times each was executed.  For each instruction, the dynamic
  312.      count of executions, and its representation as a percentage is printed.
  313.      That is followed by the cumulative execution percentage, and the count of
  314.      the number of distinct instructions of that type that were executed one
  315.      or more times, and that count represented as a percentage.
  316.  
  317. DDDDSSSSOOOO LLLLIIIISSSSTTTT
  318.      When invoked with the -_d_s_o_l_i_s_t argument, a report of summary information
  319.      about the DSOs in the execution of the program is printed.  For each DSO,
  320.      it gives the name, a count of instructions, functions, source-files, and
  321.      source-lines, the high and low addresses, and the full pathname to the
  322.      DSO.  If the DSO is ignored in computation, either because it belongs to
  323.      the SpeedShop runtime, and the -_s_h_o_w_s_s flag is not provided, or because
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. PPPPRRRROOOOFFFF((((1111))))                                                                PPPPRRRROOOOFFFF((((1111))))
  335.  
  336.  
  337.  
  338.      the DSO was excluded by being listed as with a -_x_d_s_o argument, or the DSO
  339.      was excluded by virtue of its not being listed with a -_d_s_o argument, the
  340.      DSO is flagged as ignored.
  341.  
  342. RRRREEEESSSSOOOOUUUURRRRCCCCEEEE UUUUSSSSAAAAGGGGEEEE
  343.      When invoked with the -_u_s_a_g_e argument, a report of summary usage data, as
  344.      measured by the kernel during the run, is produced.  The data consists of
  345.      both per-process (per-file) and per-system metrics.  Included are real-
  346.      time (wall clock time), user, system and wait times.  The per-process
  347.      data is shown as a sum of the data from the experiment files; the real-
  348.      time, and the system-wide statistics are printed as maxima over the data
  349.      in each file.  Included are the accounting timers, giving the time spent
  350.      in each of the various process states.  The sum of the accounting timers
  351.      should be approximately equal to the elapsed real-time, since the process
  352.      must always be in one of the states.  There is some skew in the reading
  353.      of the data, so some discrepancy should be expected.  Other summary
  354.      statistics include bytes read and written, page faults, context switches,
  355.      system calls, and process-size statistics.
  356.  
  357. DDDDIIIISSSSAAAASSSSSSSSEEEEMMMMBBBBLLLLYYYY AAAANNNNDDDD SSSSOOOOUUUURRRRCCCCEEEE LLLLIIIISSSSTTTTSSSS
  358.      When invoked with the -_d_i_s argument, an assembly listing of the program
  359.      is generated.  If the -_d_i_s argument is given as well, the source code for
  360.      the disassmebly is intermixed with it.
  361.  
  362. OOOOPPPPTTTTIIIIOOOONNNNSSSS
  363.      ----ccccaaaalllliiiippppeeeerrrrssss  [[[[nnnn1111,,,,]]]]nnnn2222
  364.           flag causes _p_r_o_f to compute the data between caliper points n1 and
  365.           n2, rather than for the entire experiment.  If n1 >= n2, an error is
  366.           reported, otherwise if n1 is negative it is set to the beginning of
  367.           the experiment, and if n2 is greater than the maximum recorded, it
  368.           is set to the maximum.  If n1 is omitted, zero is assumed.
  369.  
  370.      ----bbbb[[[[uuuutttttttteeeerrrrffffllllyyyy]]]]
  371.           or ----ggggpppprrrrooooffff causes _p_r_o_f to print a report showing the callers and
  372.           callees of each function, with inclusive time attributed to each.
  373.           For iiiiddddeeeeaaaallll experiments, the attribution is based on a heuristic,
  374.           while for the various callstack sampling/tracing experiments the
  375.           attribution is precise (although uuuusssseeeerrrrttttiiiimmmmeeee and ttttoooottttaaaallllttttiiiimmmmeeee, as well as
  376.           some ****____hhhhwwwwccccttttiiiimmmmeeee experiments are statistical in nature).  This flag is
  377.           ignored for experiments where the data does not support inclusive
  378.           calculations.
  379.  
  380.      ----pppp[[[[tttthhhhrrrreeeeaaaaddddssss]]]] <<<<pppptttthhhhrrrreeeeaaaadddd____iiiidddd1111>>>>,,,,<<<<pppptttthhhhrrrreeeeaaaadddd____iiiidddd2222>>>>,,,,............,,,,<<<<pppptttthhhhrrrreeeeaaaadddd____iiiiddddnnnn>>>>
  381.           For uuuusssseeeerrrrttttiiiimmmmeeee, ttttoooottttaaaallllttttiiiimmmmeeee, ****____hhhhwwwwccccttttiiiimmmmeeee, iiiioooo, and ffffppppeeee experiments on
  382.           applications that use pthreads (on Irix 6.5 or later), analyze data
  383.           only for the specified pthreads.  This flag is ignored for other
  384.           experiments.
  385.  
  386.      ----uuuu[[[[ssssaaaaggggeeee]]]]
  387.           Print a report on system statistics and timers.
  388.  
  389.  
  390.  
  391.  
  392.  
  393.                                                                         PPPPaaaaggggeeee 6666
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. PPPPRRRROOOOFFFF((((1111))))                                                                PPPPRRRROOOOFFFF((((1111))))
  401.  
  402.  
  403.  
  404.      ----ddddiiiissss[[[[aaaasssssssseeeemmmmbbbblllleeee]]]]
  405.           Disassemble and annotate the analyzed object code with cycle times
  406.           or number of PC samples.  This option can be used when generating
  407.           reports for iiiiddddeeeeaaaallll, ppppccccssssaaaammmmpppp, or pppprrrrooooffff____hhhhwwwwcccc experiments.
  408.  
  409.      ----SSSS((((----ssssoooouuuurrrrcccceeee))))
  410.           Disassemble and annotate the analyzed object code with cycle times
  411.           (or PC samples) and interleave the source code.  This option can be
  412.           used when generating reports for iiiiddddeeeeaaaallll, ppppccccssssaaaammmmpppp, or ****____hhhhwwwwcccc
  413.           experiments.
  414.  
  415.      ----hhhh[[[[eeeeaaaavvvvyyyy]]]]
  416.           Reports the most heavily used lines in descending order of use.
  417.           This option can be used when generating reports for iiiiddddeeeeaaaallll, ppppccccssssaaaammmmpppp,
  418.           or pppprrrrooooffff____hhhhwwwwcccc experiments.  It is ignored for other experiments.
  419.  
  420.      ----llll[[[[iiiinnnneeeessss]]]]
  421.           Like ----hhhh[[[[eeeeaaaavvvvyyyy]]]], but group lines by procedure, with procedures sorted
  422.           in descending order of use.  Within a procedure, lines are listed in
  423.           source order.  This option can be used when generating reports for
  424.           iiiiddddeeeeaaaallll, ppppccccssssaaaammmmpppp, or pppprrrrooooffff____hhhhwwwwcccc experiments.  It is ignored for other
  425.           experiments.
  426.  
  427.      ----[[[[nnnnoooo]]]]ccccoooorrrrddddffffbbbb
  428.           Disables or enables cord feedback file generation for the executable
  429.           only. Cord feedback is used to arrange procedures in the binary in
  430.           an optimal ordering, to improve both paging and instruction-cache
  431.           performance.  Users can use _c_o_r_d(_1) (or, in the near-term future,
  432.           _l_d(_1)) to actually do the procedure-ordering.
  433.  
  434.      ----ccccoooorrrrddddffffbbbbaaaallllllll
  435.           Enables cord feedback for the executable and all DSOs.
  436.  
  437.      ----ffffeeeeeeeeddddbbbbaaaacccckkkk
  438.           Produces files with information that can be used to (a) tell the
  439.           compiler how to optimize compilation of the program next time and
  440.           (b) arrange procedures in the binary in an optimal ordering.  Users
  441.           can invoke "_c_c(_1) -fb <cfb-filename>" to use the compilation-
  442.           optimization feedback file for subsequent compilations.  To disable
  443.           cord feedback, while producing compiler feedback, use the options
  444.           -_f_e_e_d_b_a_c_k -_n_o_c_o_r_d_f_b together.
  445.           Procedures are normally ordered by their measured invocation counts;
  446.           if -gprof is also specified, procedures are ordered using call graph
  447.           counts (that capture caller-callee relationships as well), rather
  448.           than invocation counts.  The cord feedback file is named <a.out>.fb
  449.           or <lib*so*>.fb.  The -_f_e_e_d_b_a_c_k option produces cord feedback for
  450.           the executable only. To get cord feedback for all the DSOs as well,
  451.           use the options -_f_e_e_d_b_a_c_k -_c_o_r_d_f_b_a_l_l together.
  452.           This option also produces a file with information that the compiler
  453.           system can use to recompile, optimizing by using measured branch
  454.           frequencies, etc.  The feedback file is produced for the executable
  455.           only.  It is named <a.out>.cfb and is a binary file.  It may be
  456.  
  457.  
  458.  
  459.                                                                         PPPPaaaaggggeeee 7777
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466. PPPPRRRROOOOFFFF((((1111))))                                                                PPPPRRRROOOOFFFF((((1111))))
  467.  
  468.  
  469.  
  470.           dumped using the fbdump(1) routine.  This option can only be used
  471.           with pixie (ideal-time) data files, and the data should be recorded
  472.           on a binary that was compiled -O0.  Recording data on binaries with
  473.           higher optimization will generate a feedback file that does not have
  474.           the appropriate correspondence between source lines and machine
  475.           code.
  476.  
  477.      ----wwwwssss  Generate a working-set file for the current caliper setting, for the
  478.           executable only.
  479.  
  480.      ----wwwwssssaaaallllllll
  481.           Generate a working-set file for the current caliper setting, for the
  482.           executable and all the non-ignored DSOs.
  483.  
  484.      ----sssshhhhoooowwwwssssssss
  485.           Enables display of functions from the SpeedShop runtime.  Normally
  486.           such functions are suppressed from the reports and computations.  In
  487.           addition, some statistics for pppprrrrooooffff's own memory usage will be
  488.           printed.
  489.  
  490.      ----ddddssssoooolllliiiisssstttt
  491.           List all the DSO's in the program and their start and end text
  492.           addresses.
  493.  
  494. OOOOUUUUTTTTPPPPUUUUTTTT CCCCOOOONNNNTTTTRRRROOOOLLLLSSSS
  495.      ----rrrreeeellll[[[[aaaattttiiiivvvveeee]]]]
  496.           Show percentage attribution in a butterfly report relative to the
  497.           central function.  The default is to show percentages as absolute
  498.           percentages over the whole run.
  499.  
  500.      ----iiiinnnncccclllluuuussssiiiivvvveeee
  501.           Sort function list by inclusive data, rather than by exclusive data.
  502.           This option can only be used when generating reports for those
  503.           experiments which have inclusive data; it is ignored for others.
  504.  
  505.      ----ccccaaaallllllllssss
  506.           Sort function list by procedure calls rather than by time.  This
  507.           option can only be used when generating reports for iiiiddddeeeeaaaallll
  508.           experiments, or for basic block counting data obtained with _p_i_x_i_e.
  509.  
  510.      ----qqqq[[[[uuuuiiiitttt]]]]  nnnn
  511.           Truncates the  -_h[_e_a_v_y], -_l[_i_n_e_s] and -_b[_u_t_t_e_r_f_l_y] listings after
  512.           the first _n procedures or lines have been listed.
  513.  
  514.      ----qqqq[[[[uuuuiiiitttt]]]] nnnn%%%%
  515.           Truncates the  -_h[_e_a_v_y], -_l[_i_n_e_s] and -_b[_u_t_t_e_r_f_l_y] listings after
  516.           those procedures or lines up to the one which takes more than _n
  517.           percent of the total.
  518.  
  519.      ----qqqq[[[[uuuuiiiitttt]]]] nnnnccccuuuummmm%%%%
  520.           Truncates the  -_h[_e_a_v_y], -_l[_i_n_e_s] and -_b[_u_t_t_e_r_f_l_y] listings after
  521.           those procedures or lines up to the one which brings the cumulative
  522.  
  523.  
  524.  
  525.                                                                         PPPPaaaaggggeeee 8888
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532. PPPPRRRROOOOFFFF((((1111))))                                                                PPPPRRRROOOOFFFF((((1111))))
  533.  
  534.  
  535.  
  536.           total to _n percent.  (For -_b[_u_t_t_e_r_f_l_y], it behaves the same as -_q_u_i_t
  537.           _n%.)  For example, "-_q[_u_i_t] _1_5" truncates each part of the listing
  538.           after 15 lines of text, "-_q[_u_i_t] _1_5%" truncates each part after the
  539.           first line that represents less than 15 percent of the whole, and
  540.           "-_q[_u_i_t] _1_5_c_u_m%" truncates each part after the line that brought the
  541.           cumulative percentage above 15 percent.
  542.  
  543.      ----ddddiiiisssslllliiiimmmmiiiitttt nnnn
  544.           Disassemble only those basic blocks with frequency >= n.
  545.  
  546.      ----nnnnhhhh  Suppress various header blocks from the output.
  547.  
  548.      SELECTIVITY OPTIONS
  549.  
  550.      ----ddddssssoooo ddddssssoooo____nnnnaaaammmmeeee
  551.           Report only on the named DSO.  Only the basename of the DSO need be
  552.           specified not the full pathname to the DSO; the ._s_o suffix is
  553.           required.  Multiple instances of the -_d_s_o flag can be given, and the
  554.           executable is considered a DSO, like any other.  All the DSOs from
  555.           an experiment can be listed with the ----ddddssssoooolllliiiisssstttt flag.
  556.  
  557.      ----xxxxddddssssoooo ddddssssoooo____nnnnaaaammmmeeee
  558.           Exclude the named DSO from any reports.  Only the basename of the
  559.           DSO need be specified not the full pathname to the DSO; the ._s_o
  560.           suffix is required.  Multiple instances of the ----xxxxddddssssoooo flag can be
  561.           given.
  562.  
  563.      ----oooo[[[[nnnnllllyyyy]]]] pppprrrroooocccceeeedddduuuurrrreeee____nnnnaaaammmmeeee
  564.           If you use one or more ----oooo[[[[nnnnllllyyyy]]]] options, the profile listing includes
  565.           only the named procedures, rather than the entire program. If any
  566.           option uses an uppercase "O" for ----OOOO[[[[nnnnllllyyyy]]]],,,, _p_r_o_f uses only the named
  567.           procedures, rather than the entire program, as the base upon which
  568.           it calculates percentages.
  569.  
  570.      ----eeee[[[[xxxxcccclllluuuuddddeeee]]]] pppprrrroooocccceeeedddduuuurrrreeee____nnnnaaaammmmeeee
  571.           If you use one or more ----eeee[[[[xxxxcccclllluuuuddddeeee]]]] options, the profiler omits the
  572.           specified procedure from the listing.  If any option uses an
  573.           uppercase "E" for ----EEEE[[[[xxxxcccclllluuuuddddeeee]]]] , prof also omits that procedure from
  574.           the base upon which it calculates percentages.
  575.  
  576.      CPU OPTIONS
  577.  
  578.      _p_r_o_f normally uses the scheduling model for the processor on which it is
  579.      being run to perform the analysis.  The user can override the default
  580.      with any of the following options:
  581.  
  582.      {{{{----rrrr11110000000000000000 |||| ----rrrr8888000000000000 |||| ----rrrr5555000000000000 |||| ----rrrr4444000000000000 |||| ----rrrr3333000000000000}}}}
  583.           Note that these options are only meaningful for ideal time and
  584.           pixie-counts data.
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.                                                                         PPPPaaaaggggeeee 9999
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598. PPPPRRRROOOOFFFF((((1111))))                                                                PPPPRRRROOOOFFFF((((1111))))
  599.  
  600.  
  601.  
  602.      ----cccclllloooocccckkkk _m_e_g_a_h_e_r_t_z
  603.           Set the CPU clock speed to  _m_e_g_a_h_e_r_t_z  MHz.  Alters the appropriate
  604.           parts of the listing to reflect the clock speed.  The default value
  605.           is the clock speed of the machine on which the experiment was
  606.           performed.
  607.  
  608.      ----ccccyyyycccclllleeee _n_a_n_o_s_e_c_o_n_d
  609.           Set cycle time to _n_a_n_o_s_e_c_o_n_d ns. This is the same as ----cccclllloooocccckkkk
  610.           1000/_n_a_n_o_s_e_c_o_n_d.
  611.  
  612. DDDDEEEEBBBBUUUUGGGGGGGGIIIINNNNGGGG OOOOPPPPTTTTIIIIOOOONNNNSSSS
  613.      ----ddddeeeebbbbuuuugggg::::ddddeeeebbbbuuuugggg____ffffllllaaaaggggssss
  614.           Where debug_flags can be combinations of the following.
  615.  
  616.            GPROF_FLAG      0x00000001
  617.  
  618.            COUNTS_FLAG     0x00000002
  619.  
  620.            SAMPLE_FLAG     0x00000004
  621.  
  622.            MISS_FLAG       0x00000008
  623.  
  624.            FEEDBACK_FLAG   0x00000010
  625.  
  626.            CORD_FLAG       0x00000020
  627.  
  628.            USERPC_FLAG     0x00000040
  629.  
  630.            MDEBUG_FLAG     0x00000080
  631.  
  632.            BEAD_FLAG       0x00000100
  633.  
  634. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  635.      _p_r_o_f prints warnings and fatal errors on stderr.  With inclusive cycle
  636.      counting, _p_r_o_f prints a list of functions at the end which are called but
  637.      not defined. Any functions starting with __r_l_d listed here is normal
  638.      behavior. They appear because _r_l_d is not instrumented.
  639.  
  640.      One way to sanity-check inclusive cycle counts is to look at the
  641.      percentage cycles for __start().  If the value is anything less than 98-
  642.      99%, the inclusive report is suspect.  Look for other warnings which
  643.      indicate that _p_r_o_f didn't take into account certain procedures.
  644.  
  645.      There are a number of known cases when _p_r_o_f fails to list cycles of a
  646.      procedure in the inclusive listing.  The reasons can be one of the
  647.      following:
  648.  
  649.         - init & fini sections, mips stubs are not part of any procedure.
  650.  
  651.         - calls to procedures which don't use a jump and link are
  652.           not recognized as procedure calls.
  653.  
  654.  
  655.  
  656.  
  657.                                                                        PPPPaaaaggggeeee 11110000
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664. PPPPRRRROOOOFFFF((((1111))))                                                                PPPPRRRROOOOFFFF((((1111))))
  665.  
  666.  
  667.  
  668.         - executions of global procedures with same name in different DSOs.
  669.           In this case, only one of them is listed.
  670.  
  671.      All these exceptions are listed at the end of the -_g_p_r_o_f listing, under a
  672.      separate section.
  673.  
  674. LLLLIIIIMMMMIIIITTTTAAAATTTTIIIIOOOONNNNSSSS
  675.      With both pc-sampling and basic block counting, _p_r_o_f may report times for
  676.      procedures named with a prefix of *_D_F*, for example *_D_F*__h_e_l_l_o._i_n_i_t__2. DF
  677.      stands for _D_u_m_m_y _F_u_n_c_t_i_o_n, and indicates cycles spent in parts of text
  678.      which are not in any function, for example, init and fini sections, and
  679.      MIPS.stubs sections.  For pc-sampling, and hardware counter overflow pc-
  680.      sampling, a dummy function, *_D_F*__O_t_h_e_r is used to report sampling hits in
  681.      an overflow bin; these hits include time spent in _r_l_d, and any other text
  682.      regions not listed in any DSO.
  683.  
  684.      If any of the object files linked into the application have been stripped
  685.      of line-number information (with _l_d -_x for example), _p_r_o_f warns about the
  686.      affected procedures.  The instruction counts for such procedures are
  687.      shown as a procedure total, not on a per-basic-block basis.  Where a line
  688.      number would normally appear in a report on a function without line
  689.      numbers question marks appear instead.
  690.  
  691.      _p_r_o_f does not take into account interactions between basic blocks in
  692.      ideal time runs. _p_r_o_f computes the cycles for one execution of a basic
  693.      block, assuming all registers are free at entry to the block, and it
  694.      multiplies this count by the number of times that basic block is
  695.      executed.  In real programs, a block may be entered with a result not yet
  696.      ready in a register, or with a function unit busy, so the cycle count
  697.      computed could be either higher or lower than the correct value.
  698.      Extending the computations to include inter-block state would be
  699.      prohibitively expensive.
  700.  
  701.      When run on a program using shared libraries, _p_r_o_f sometimes combines the
  702.      times of real but anonymous procedures in a shared library into the
  703.      preceding (according the library memory layout) externally visible
  704.      function.  The times reported for your procedures are not affected by
  705.      this attribution-error, which is normally minor.
  706.  
  707.      _p_r_o_f cannot be run on programs which have been stripped.
  708.  
  709.      Compiler optimization level 3 does procedure inlining.  This can result
  710.      in extremely misleading profiles since the time spent in the inlined
  711.      procedure shows up in the profile as time spent in the procedure into
  712.      which it was inlined.  It is generally better to use compiler
  713.      optimization level 2 or less when gathering an execution profile.
  714.  
  715.      Fortran alternate entry point times are attributed to the main
  716.      function/subroutine, since there is no general way for _p_r_o_f to separate
  717.      the times for the alternate entries.
  718.  
  719.  
  720.  
  721.  
  722.  
  723.                                                                        PPPPaaaaggggeeee 11111111
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730. PPPPRRRROOOOFFFF((((1111))))                                                                PPPPRRRROOOOFFFF((((1111))))
  731.  
  732.  
  733.  
  734. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  735.      speedshop(1), ssrun(1), ssdump(1), sscord(1), ssorder(1), pixie(1),
  736.      fbdump(1)
  737.  
  738.  
  739.  
  740.  
  741.  
  742.  
  743.  
  744.  
  745.  
  746.  
  747.  
  748.  
  749.  
  750.  
  751.  
  752.  
  753.  
  754.  
  755.  
  756.  
  757.  
  758.  
  759.  
  760.  
  761.  
  762.  
  763.  
  764.  
  765.  
  766.  
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.                                                                        PPPPaaaaggggeeee 11112222
  790.  
  791.  
  792.  
  793.